Criminal Risk Exact Verification API

This document highlights the Criminal Risk Exact Verification API details.

API Description

Objective

The Criminal Risk Exact Verification API gathers important information such as the individual's exact name and address etc and provides comprehensive risk assessment details regarding the individual's potential involvement in criminal activities.

Input	Output
The details of the individual being assessed for potential criminal involvement	The details corresponding to the criminal records fetched for the individual. The complete list of output fields is available in the Success Response Details section.

info

The Criminal Risk Exact Verification API employs exact field matching techniques to compare the input details against the database.

API URL

https://ind-engine.thomas.hyperverge.co/v1/criminalRiskExact

API Endpoint

criminalRiskExact

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

Method - POST

Headers

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value.
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table outlines the parameters required in the API's request body:

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
name	The name of the individual	Mandatory	Not Applicable	Not Applicable
address	The residential address of the individual	Optional	Not Applicable	Not Applicable
fathername	The father name of the individual	Optional	Not Applicable	Not Applicable
dob	The date of birth (dob) of the individual	Optional	Not Applicable	Not Applicable
source	The source or origin of the case information- eCourt, High Court or the Supreme Court	Optional	"ecourt", "hc" and "sc"	Not Applicable
caseCategory	The category of the case- whether the report represents a civil or a criminal case	Optional	"civil" , "criminal"	Not Applicable
type	The role of the individual in the case	Optional	"petitioner" , "respondent"	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/criminalRiskExact' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "name": "<Enter_the_name>",
    "dob": "<Enter_the_Date_of_Birth>",
    "fatherName": "<Enter_the_father_name>",
    "address": "<Enter_the_address>",
    "caseCategory": "<Enter_your_case_category>",
    "source": "<Enter_the_source>",
    "type": "<Enter_respondent_or_petitioner>"
}'

Success Responses

First API Hit

The following JSON code snippet demonstrates a success response from the API when it is triggered for the first time ever with the new data:

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "message": "<Process_Status_Message>"
  },
  "metaData": {
    "requestId": "<Unique_Request_Identifier>"
  }
}

Second API Hit

The following JSON code snippet demonstrates a success response from the API when it is triggered again

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "total": 6,
        "cases": [
            {
                "address": "<address>",
                "addressScore": 65,
                "algoRisk": "<risk_level>",
                "asrInfo": "<act_info>",
                "businessCategory": "<category>",
                "caseCategory": "<case_category>",
                "caseCode": "<case_code>",
                "caseFilter": "<filter>",
                "caseStatus": "<status>",
                "caseType": "<type>",
                "caseTypeCode": "<type_code>",
                "caseTypeDescription": "",
                "caseTypeName": "<type_name>",
                "caseYear": "<year>",
                "cnr": "<cnr>",
                "courtCode": "<court_code>",
                "courtName": "<court_name>",
                "decisionDate": "<decision_date>",
                "distCode": "<district_code>",
                "distMatch": "<match_status>",
                "distName": "<district_name>",
                "falconScore": "<score>",
                "fatherMatchType": "<match_type>",
                "firNo": "<fir_number>",
                "firstHearingDate": "<hearing_date>",
                "id": null,
                "isDistrict": 1,
                "isState": 1,
                "jurisdiction": "<jurisdiction_status>",
                "jurisdictionType": "<jurisdiction_type>",
                "link": "<link>",
                "matchedAddress": "<matched_address>",
                "matchedName": "<matched_name>",
                "maxWordsMatched": "<word_count>",
                "md5": "<hash>",
                "name": "<name>",
                "nameMatchType": "<match_type>",
                "nameScore": "<score>",
                "natureOfDisposal": "<disposal_status>",
                "oparty": "<opposing_party>",
                "policeStation": "<station>",
                "purposeOfHearing": "<purpose>",
                "rawAddress": "<raw_address>",
                "ref": "<reference>",
                "registrationDate": "<date>",
                "score": "<score>",
                "source": "<source>",
                "stateCode": "<state_code>",
                "stateMatch": "<state_match>",
                "stateName": "<state_name>"
            }
        ]
    },
    "metaData": {
        "requestId": "<request_id>"
    }
}

Note

The Criminal Risk Exact Verification API needs to be triggered twice for fresh data. After the first call, there should be a time gap of 4 to 5 seconds before making the second call. Only after the second call will the data be established in the database. Once the data is stored, subsequent requests will return the details with just the first API call.

Success Response Details

The following table outlines the details of the success response from the API:

Parameter	Type	Description
status	String	The status of the response.
statusCode	Integer	The HTTP status code of the response.
result.total	Integer	The total number of cases returned in the response.
result.cases	Array	The list of cases returned by the API. Each case contains detailed information about the criminal record.
result.cases.address	String	The address associated with the case.
result.cases.addressScore	Integer	A score indicating the match quality of the address.
result.cases.algoRisk	String	The risk level calculated by the algorithm (e.g., "very high risk").
result.cases.asrInfo	String	The legal code and sections under which the case is filed.
result.cases.businessCategory	String	The business category related to the case (e.g., "Serious").
result.cases.caseCategory	String	The category of the case (e.g., "criminal").
result.cases.caseCode	String	The unique case code.
result.cases.caseFilter	String	The filter applied to the case (e.g., "POLICE_CASE").
result.cases.caseStatus	String	The current status of the case (e.g., "CASE DISPOSED").
result.cases.caseType	String	The type of the case (e.g., "Bail Matters").
result.cases.caseTypeCode	String	A code for the case type (e.g., "70").
result.cases.caseTypeDescription	String	A description of the case type (if available).
result.cases.caseTypeName	String	The name of the case type (e.g., "Bail Matters").
result.cases.caseYear	Integer	The year the case was filed.
result.cases.cnr	String	The Case Number Registration (CNR) of the case.
result.cases.courtCode	String	The code for the court where the case was heard.
result.cases.courtName	String	The name of the court handling the case.
result.cases.decisionDate	String (Date)	The date the decision was made in the case.
result.cases.distCode	String	The district code where the case is filed.
result.cases.distMatch	Boolean	The match status of the district.
result.cases.distName	String	The name of the district where the case is filed.
result.cases.falconScore	Integer	The calculated risk score for the case.
result.cases.fatherMatchType	String	The match type for the father's details in the case (if available).
result.cases.firNo	String	The FIR number associated with the case.
result.cases.firstHearingDate	String (Date)	The date of the first hearing of the case.
result.cases.id	String	The unique ID for the case, if available.
result.cases.isDistrict	Boolean	Indicates if the case is under district jurisdiction (1 for yes, 0 for no).
result.cases.isState	Boolean	Indicates if the case is under state jurisdiction (1 for yes, 0 for no).
result.cases.jurisdiction	String	Indicates if the case falls under jurisdiction.
result.cases.jurisdictionType	String	The type of jurisdiction (e.g., "STATE").
result.cases.link	String (URL)	A URL link to more details about the case.
result.cases.matchedAddress	String	The address matched with the input data.
result.cases.matchedName	String	The name matched with the input data.
result.cases.maxWordsMatched	Integer	The maximum number of words matched in the case.
result.cases.md5	String	A unique MD5 hash for the case record.
result.cases.name	String	The name associated with the case.
result.cases.nameMatchType	String	The match type for the name (e.g., "PARTIAL_FUZZY").
result.cases.nameScore	Integer	The score indicating how closely the name matches.
result.cases.natureOfDisposal	String	The nature of how the case was disposed (e.g., "Contested--ALLOWED").
result.cases.oparty	String	The opposing party in the case.
result.cases.policeStation	String	The name of the police station associated with the case.
result.cases.purposeOfHearing	String	The purpose of the hearing (if available).
result.cases.rawAddress	String	The raw address associated with the case.
result.cases.ref	String	A unique reference ID for the case.
result.cases.registrationDate	String (Date)	The date the case was registered.
result.cases.score	Integer	The overall match score for the case.
result.cases.source	String	The source from where the case information is obtained (e.g., "ecourt").
result.cases.stateCode	String	The state code for the case.
result.cases.stateMatch	Boolean	The match status of the state.
result.cases.stateName	String	The name of the state where the case is filed.
result.cases.totalNameMatch	Integer	The total number of name matches found.
result.cases.type	String	The type of case (e.g., criminal or civil).
result.cases.underActs	String	The legal acts under which the case is filed.
result.cases.underSections	String	The sections of the legal acts under which the case is filed.
result.cases.uniqCaseId	String	A unique case ID.
result.cases.verifycode	String	The verification code for the case.
result.cases.wordsMatched	Integer	The words from the input that matched with the case information.
result.cases.year	Integer	The year in which the case is filed, if available.

Error Responses

The following are the error responses from the API:

Missing Input - name

{
    "message": "name should not be empty",
    "statusCode": 400,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Missing Input - caseCategory

{
    "message": "Input Validation Error: is not one of enum values: civil,criminal",
    "statusCode": 400,
    "status": "failure"
}

Missing Input - type

{
    "message": "Input Validation Error: is not one of enum values: petitioner,respondent",
    "statusCode": 400,
    "status": "failure"
}

Missing Input - source

{
    "message": "Input Validation Error: is not one of enum values: source",
    "statusCode": 400,
    "status": "failure"
}

Missing/Invalid Credentials

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

Internal Server Error

{
    "message": "Internal Server Error",
    "statusCode": 500,
    "status": "failure"
}

Error Response Details

A failure or error response from the module contains a failure status, with a relevant status code and error message. The following table lists all error responses:

Status Code	Error Message	Error Description
400	name should not be empty	The request has null or undefined value for name parameter
400	Input Validation Error: is not one of enum values: civil,criminal	The input parameter caseCategory is provided with values other than "civil"/"criminal"
400	Input Validation Error: is not one of enum values: petitioner,respondent	The input parameter type is provided with values other than "petitioner"/"respondent"
400	Input Validation Error: is not one of enum values: ecourt,hc,sc	The input parameter source is provided with values other than "ecourt", "hc","sc"
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution